Skip to content

docs(claudemd): document full set of v2-pinned DSM APIs#90

Merged
cmeans-claude-dev[bot] merged 2 commits into
mainfrom
docs/v2-pin-claudemd
May 2, 2026
Merged

docs(claudemd): document full set of v2-pinned DSM APIs#90
cmeans-claude-dev[bot] merged 2 commits into
mainfrom
docs/v2-pin-claudemd

Conversation

@cmeans-claude-dev
Copy link
Copy Markdown
Contributor

@cmeans-claude-dev cmeans-claude-dev Bot commented May 2, 2026 •
edited by cmeans
Loading

Summary

Closes #42.

The "Version pinning" bullet under ## Key Conventions → DSM API Client previously named only CopyMove, Delete, and Search as v2-pinned. Audit of src/ (grep -rn "max_version=2\|min(.*max_version, 2)") found two more pins the bullet didn't mention:

The bullet now lists all five APIs with file pointers and the rationale: "removing any of these pins reintroduces silent failures on DSM 7.x — the v3 request format DSM advertises is metadata, not a mandate." A future refactor can't innocently strip a pin and rediscover the bug.

Audit verification

$ grep -rn "max_version=2\|min(.*max_version, 2)" src/
src/mcp_synology/modules/filestation/search.py:78:    search_version = min(2, client.negotiate_version("SYNO.FileStation.Search", max_version=2))
src/mcp_synology/modules/filestation/metadata.py:80:    getinfo_version = min(2, client.negotiate_version("SYNO.FileStation.List", max_version=2))
src/mcp_synology/modules/filestation/operations.py:309:    copymove_version = min(2, client.negotiate_version("SYNO.FileStation.CopyMove", max_version=2))
src/mcp_synology/modules/filestation/operations.py:467:    delete_version = min(2, client.negotiate_version("SYNO.FileStation.Delete", max_version=2))
src/mcp_synology/core/client.py:354:        resolved_version = version if version is not None else min(info.max_version, 2)

5 pins → 5 mentions in the convention. No undocumented pins remain.

Files changed

  • CLAUDE.md — single bullet rewritten under ## Key Conventions → DSM API Client
  • CHANGELOG.md — ### Changed entry under ## Unreleased

Test plan

  • CI green
  • grep -c "Upload\|List getinfo" CLAUDE.md returns ≥1
  • No code change, so functional smoke not needed

🤖 Generated with Claude Code

@cmeans-claude-dev @claude
docs(claudemd): document full set of v2-pinned DSM APIs
5403617 
Closes #42.

The "Version pinning" bullet under `## Key Conventions →
DSM API Client` previously named only CopyMove, Delete, and
Search as v2-pinned. Audit of src/ (`grep -rn "max_version=2
\|min(.*max_version, 2)"`) found two more pins the bullet
didn't mention:

- SYNO.FileStation.Upload (core/client.py::upload_file:354)
  — Upload is a special-case multipart POST not routed
  through request(), so its v2 pin lives in the upload code
  path with `min(info.max_version, 2)`. v3 advertises a JSON
  body the multipart code can't speak.

- SYNO.FileStation.List getinfo (modules/filestation/metadata
  .py:80) — added by PR #77 to dodge the v3 multipath quirk
  that surfaced as #68.

Bullet now lists all five with file pointers and the rationale
("removing any of these pins reintroduces silent failures on
DSM 7.x") so a future refactor can't innocently strip a pin
and rediscover the bug.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added the Awaiting CI Dev complete, waiting for CI/Codecov to pass before QA label May 2, 2026
@cmeans-claude-dev @claude
docs: backfill PR #90 reference in CHANGELOG entry
337ae8f 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added Ready for QA Dev work complete — QA can begin review and removed Awaiting CI Dev complete, waiting for CI/Codecov to pass before QA labels May 2, 2026
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented May 2, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@cmeans cmeans added QA Active QA is actively reviewing; Dev should not push changes and removed Ready for QA Dev work complete — QA can begin review labels May 2, 2026
cmeans
cmeans reviewed May 2, 2026
View reviewed changes
Copy link
Copy Markdown
Owner

@cmeans cmeans left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA Round 1 — PASS (no findings)

Doc-only PR on head 337ae8f. 2 files / +3 / -1.

Verified

Audit claim: Re-ran grep -rn "max_version=2\|min(.*max_version, 2)" src/ independently — found exactly the 5 pins the PR body lists, in the same locations:

API File Line
CopyMove modules/filestation/operations.py 309
Delete modules/filestation/operations.py 467
Search modules/filestation/search.py 78
List getinfo modules/filestation/metadata.py 80
Upload core/client.py 354

I also ran a broader grep -rnE "version=2|min\(2," to catch alternative patterns the PR's regex might miss. One additional hit: src/mcp_synology/modules/__init__.py:120 result = await handler(negotiated_version=2, **kwargs). That's illustrative docstring example code inside the VersionedHandler class, not an actual v2 pin — false positive. PR's 5-pin enumeration is exhaustive.

Updated bullet: Now names all five APIs, each with a file pointer; explains why Upload's pin lives in core/client.py (multipart POST not routed through request()); credits #77 for the List getinfo pin and ties it to #68; and closes with the rationale ("removing any of these pins reintroduces silent failures on DSM 7.x — the v3 request format DSM advertises is metadata, not a mandate") so a future refactor can't innocently strip a pin.

CHANGELOG: New ### Changed entry under ## Unreleased, slotted above the existing #88 entry. KaC ordering preserved (### Added block above ### Changed block).

Test plan

  • CI green — 12/12 required incl. vdsm integration tests SUCCESS on this exact head.
  • grep -c "Upload\|List getinfo" CLAUDE.md returned 1 (≥1 satisfied).
  • No code change → no functional smoke needed.

Disposition

Ready for QA Signoff applied as the final act. With this in, #51's LOW/docs queue drops from 4 to 3 (#43, #45, #46 remain).

@cmeans
Copy link
Copy Markdown
Owner

cmeans commented May 2, 2026

Applying Ready for QA Signoff — clean doc-only PR. Independently re-ran the audit grep + a broader pattern scan; PR's 5-pin enumeration (CopyMove, Delete, Search, List getinfo, Upload) is exhaustive. Updated CLAUDE.md bullet correctly names all five with file pointers and the rationale. CHANGELOG ## Unreleased ### Changed entry slotted above #88's. CI 12/12 green incl. vdsm. All 3 test-plan checkboxes flipped. Closes #42 — #51's LOW/docs queue drops to #43, #45, #46.

@cmeans cmeans added Ready for QA Signoff QA passed — ready for maintainer final review and merge QA Approved Manual QA testing completed and passed and removed QA Active QA is actively reviewing; Dev should not push changes Ready for QA Signoff QA passed — ready for maintainer final review and merge labels May 2, 2026
cmeans
cmeans approved these changes May 2, 2026
View reviewed changes
Copy link
Copy Markdown
Owner

@cmeans cmeans left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@cmeans-claude-dev cmeans-claude-dev Bot merged commit b9afaea into main May 2, 2026
38 checks passed
@cmeans-claude-dev cmeans-claude-dev Bot deleted the docs/v2-pin-claudemd branch May 2, 2026 02:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cmeans cmeans cmeans approved these changes

Assignees

No one assigned

Labels

QA Approved Manual QA testing completed and passed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document Upload v2 pin in CLAUDE.md alongside CopyMove/Delete/Search

2 participants

@codecov-commenter @cmeans